---
title: JSONPath
description: A cheatsheet for JSONPath syntax and filters.
---

<Note>
  JSONPath and dot notation should be used to:
  - Get single values from a nested JSON object
  - Get values from JSON arrays via indexing and slicing
  - Filter lists of JSONs using simple conditions (e.g. `==`, `!=`, `>`, `>=`, `<`, `<=`)

  For advanced filtering, we recommend using the `core.transform.filter` action.
</Note>

<Info>
  Tracecat's JSONPath implementation is based on [jsonpath-ng](https://github.com/h2non/jsonpath-ng?tab=readme-ov-file#jsonpath-syntax).
</Info>

This cheatsheet covers the basics of JSONPath syntax and filters.

## Basic Syntax

<Note>
  Replace `$` with `ACTIONS.<action_name>.result` or `TRIGGER` [expression contexts](/quickstart/expressions).
</Note>

For the following examples, we'll use the following JSON:

```json
{
  "data": {
    "users": [
      { "id": 1, "name": "John", "age": 30, "active": true, "score": 85 },
      { "id": 2, "name": "Jane", "age": 25, "active": true, "score": 92 },
      { "id": 3, "name": "Bob", "age": 35, "active": false, "score": 78 },
      { "id": 4, "name": "Alice", "age": 28, "active": true, "score": 95 }
    ],
    "settings": {
      "theme": "dark",
      "notifications": true
    },
    // Fields with special characters
    "alert.sample.data": {
      "id": 1,
      "name": "John",
      "age": 30,
      "active": true,
      "score": 85
    },
    "field-with-dashes": "value",
    "$field": "value",
    "field:with:colons": "value",
    "field@symbol": "value",
    "field with spaces": "value",
    "field#hash": "value"
  }
}
```

### Dot Notation

```php
$.data.settings.theme  # Select the theme property
```

### Special Characters

Fields containing special characters like dots, dashes, or starting with `$` can be accessed using quotes:

```php
$.data."alert.sample.data"  # Access field containing dots
$.data."field-with-dashes"  # Access field containing dashes
$.data."$field"  # Access field starting with $
$.data."field:with:colons"  # Access field containing colons
$.data."field@symbol"  # Access field containing @ symbol
$.data."field with spaces"  # Access field containing spaces
$.data."field#hash"  # Access field containing hash symbol
```

### Array Indexing

```php
$.data.users[*]  # Select all users
$.data.users[0]  # Select the first user
$.data.users[-1]  # Select last user
$.data.users[*].name  # Select all user names
$.data.users[0].name  # Select the name of the first user
$.data.users[?(@.id==1)]  # Select user with id=1
$.data.users[*].roles[0]  # Select the first role of each user
$.data.settings.*  # Select all properties of settings
```

## Filters

### Basic Filters
```php
$.data.users[?(@.age > 30)]  # Users over 30
$.data.users[?(@.active == true)]  # Active users
$.data.users[?(@.name == "John")]  # User named John
$.data.users[?(@.score >= 90)]  # Users with score 90 or higher
```

### Comparison Operators
```php
$.data.users[?(@.age != 30)]  # Users not age 30
$.data.users[?(@.score >= 85)]  # Users with score 85 or higher
$.data.users[?(@.score < 80)]  # Users with score under 80
$.data.users[?(@.active !== false)]  # Users that are not inactive
```
